Skip to content

feat(search-api-graphql): write the GraphQL contract of a schema module to a file - #722

Merged
ddeboer merged 2 commits into
mainfrom
feat/print-sdl-bin
Aug 12, 2026
Merged

feat(search-api-graphql): write the GraphQL contract of a schema module to a file#722
ddeboer merged 2 commits into
mainfrom
feat/print-sdl-bin

Conversation

@ddeboer

@ddeboer ddeboer commented Aug 12, 2026

Copy link
Copy Markdown
Member

A deployment that mounts a schema-declaration module usually wants its GraphQL
contract as a published fileschema.graphql, the thing consumers read
and pull requests diff. Today each such repository writes that generator
itself; Linked Open Limburg has one, and it is generic apart from its paths.
This moves it here.

search-print-sdl

search-print-sdl --module ./dist/module.js --out ./schema.graphql

Loads the module through loadSchemaModule from @lde/search/module – the
same loader, the same validation and the same schemaOptions forwarding the
indexer and the served API use – so the printed file cannot describe a
different API from the one served. Without --out the SDL goes to standard
output.

printSchemaModuleSdl is the same thing from code, on a
@lde/search-api-graphql/print-sdl entry point rather than the barrel: it
reads the filesystem, and the main entry point stays runtime-agnostic for
consumers bundling the fetch handler for workers or the edge (mirroring how
@lde/search keeps loadSchemaModule on /module).

Formatting

The output is formatted with the Prettier configuration that applies to the
output path, .editorconfig included – the Prettier CLI reads it by default
and the Node API does not, so leaving it off would have a repository’s
prettier --write pre-commit hook reformat what was just written, the two
overwriting each other in turn and producing a permanent spurious diff in the
regenerate-and-commit workflow. The graphql parser is named outright, so an
output path Prettier cannot map to a parser (.sdl) formats instead of failing.

Prettier is an optional peer dependency: the consumer’s own version formats
the file, which is the point – a bundled copy at another version could reopen
the same ping-pong – and it stays out of the @lde/search-api-server image.
--no-format never loads it.

Also here

@lde/search-api-server validated its optional module exports with its own
copy of a check this writer needed too. That check now lives once, as
optionalObjectExport in @lde/search/module, next to the loader that hands
back the raw exports for consumers to validate.

Two coverage baselines move down: both packages are at 100% for every file
this touches, and the aggregate branch percentage drops only because the
deleted duplicate’s covered branches left the denominator.

Note on the lockfile

package-lock.json carries ~60 lines beyond the dependencies added here:
version drift nx release left behind by bumping package manifests without
syncing the lock. Any npm install reproduces it; hand-editing it back out is
riskier than the noise.

- add optionalObjectExport to @lde/search/module: reads an optional
  object-shaped export of a loaded schema module, naming the module and
  the export when it is not a plain object
- have @lde/search-api-server use it for schemaOptions and engineOptions
  instead of its own copy, so the two cannot drift apart
- re-anchor the branch baselines the deleted copy carried
…le to a file

- add printSchemaModuleSdl on a @lde/search-api-graphql/print-sdl entry
  point: loads a mounted schema-declaration module the way the indexer
  and the served API load it, forwards its schemaOptions, and prints the
  SDL. A separate entry point because it reads the filesystem, while the
  main one stays runtime-agnostic
- expose it as the search-print-sdl bin, so a deployment regenerates and
  commits its published surface without a script of its own
- format with the Prettier configuration that applies to the output
  path, .editorconfig included, so a formatting pre-commit hook and this
  writer cannot spell the same schema differently and overwrite each
  other in turn. Prettier is an optional peer: the consumer's own
  version formats the file, and --no-format never loads it
- name the graphql parser outright, so an output path Prettier cannot
  map to a parser formats instead of failing
- resync package-lock.json, which carries version drift from earlier
  releases beyond the dependencies added here
@ddeboer
ddeboer force-pushed the feat/print-sdl-bin branch from c63761e to 4abf010 Compare August 12, 2026 14:04
@ddeboer
ddeboer merged commit 756d574 into main Aug 12, 2026
4 checks passed
@ddeboer
ddeboer deleted the feat/print-sdl-bin branch August 12, 2026 18:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant